/**
 * ============万年历路由配置模块开始===========
 * 万年历路由配置 - Calendar Routes Configuration
 * 
 * 功能说明：
 * - 提供万年历相关的API端点
 * - 支持指定日期和今日万年历信息查询
 * - 支持月历信息和吉日查询
 * - 集成农历计算服务
 * - 提供RESTful风格的API接口
 * 
 * 依赖模块：
 * - express: Web框架，提供路由功能
 * - LunarService: 农历计算服务，提供万年历核心功能
 * 
 * API端点说明：
 * - GET /calendar/info - 获取指定日期的万年历信息
 * - GET /calendar/today - 获取今日万年历信息
 * - GET /calendar/month - 获取指定月份的月历信息
 * - GET /calendar/auspicious - 获取吉日信息
 * 
 * 应用场景：
 * - 万年历应用的数据接口
 * - 传统文化相关应用
 * - 日程规划和决策辅助
 * - 节日和节气查询
 * 
 * 设计原则：
 * - RESTful API设计
 * - 统一的响应格式
 * - 完善的错误处理
 * - 参数验证和安全性
 * 
 * Provides comprehensive calendar API endpoints with lunar calculation features
 */

// 导入必要的依赖包 - Import necessary dependencies
import express from 'express';                           // Web框架 - Web framework
import { LunarService } from '../services/lunar_service.js'; // 农历服务 - Lunar service

/**
 * ============路由实例和服务初始化开始===========
 * 创建路由实例和服务实例
 * Create router instance and service instance
 * 
 * 功能说明：
 * - 创建Express路由实例用于定义API端点
 * - 初始化LunarService实例用于万年历计算
 * - 确保服务的单例模式使用
 */
const router = express.Router();                         // 创建路由实例 - Create router instance
const lunarService = new LunarService();                 // 创建农历服务实例 - Create lunar service instance

/**
 * ============获取指定日期万年历信息功能开始===========
 * 获取指定日期的万年历信息
 * Get calendar information for specified date
 * 
 * @param {Object} req - Express请求对象
 * @param {Object} req.query - 查询参数
 * @param {string} req.query.year - 年份（必需）
 * @param {string} req.query.month - 月份（必需）
 * @param {string} req.query.day - 日期（必需）
 * @param {Object} res - Express响应对象
 * @returns {Object} JSON响应包含万年历信息
 * 
 * 功能说明：
 * - 根据用户提供的年月日获取详细万年历信息
 * - 包含公历、农历、节气、节日、宜忌等信息
 * - 支持历史日期和未来日期查询
 * - 提供完整的传统文化信息
 * 
 * 查询参数：
 * - year: 年份，4位数字，如2024
 * - month: 月份，1-12的数字
 * - day: 日期，1-31的数字
 * 
 * 响应格式：
 * {
 *   "success": true,
 *   "data": {
 *     "solar": {...},      // 公历信息
 *     "lunar": {...},      // 农历信息
 *     "festivals": [...],  // 节日信息
 *     "solarTerms": [...], // 节气信息
 *     "suitable": [...],   // 宜做事项
 *     "avoid": [...]       // 忌做事项
 *   },
 *   "message": "获取万年历信息成功"
 * }
 * 
 * 错误处理：
 * - 400: 参数缺失或格式错误
 * - 500: 服务器内部错误
 */
const getCalendarInfo = async (req, res) => {
  try {
    // 第一步：提取查询参数 - Step 1: Extract query parameters
    const { year, month, day } = req.query;
    
    // 第二步：参数验证 - Step 2: Parameter validation
    if (!year || !month || !day) {
      return res.status(400).json({
        success: false,
        message: '缺少必要参数：年、月、日 - Missing required parameters: year, month, day',
        error: 'MISSING_PARAMETERS'
      });
    }
    
    // 验证参数格式 - Validate parameter format
    const yearNum = parseInt(year);
    const monthNum = parseInt(month);
    const dayNum = parseInt(day);
    
    if (isNaN(yearNum) || isNaN(monthNum) || isNaN(dayNum)) {
      return res.status(400).json({
        success: false,
        message: '参数格式错误：年月日必须为数字 - Invalid parameter format: year, month, day must be numbers',
        error: 'INVALID_FORMAT'
      });
    }
    
    // 验证参数范围 - Validate parameter range
    if (yearNum < 1900 || yearNum > 2100) {
      return res.status(400).json({
        success: false,
        message: '年份范围错误：支持1900-2100年 - Year range error: supports 1900-2100',
        error: 'YEAR_OUT_OF_RANGE'
      });
    }
    
    if (monthNum < 1 || monthNum > 12) {
      return res.status(400).json({
        success: false,
        message: '月份范围错误：支持1-12月 - Month range error: supports 1-12',
        error: 'MONTH_OUT_OF_RANGE'
      });
    }
    
    if (dayNum < 1 || dayNum > 31) {
      return res.status(400).json({
        success: false,
        message: '日期范围错误：支持1-31日 - Day range error: supports 1-31',
        error: 'DAY_OUT_OF_RANGE'
      });
    }
    
    // 第三步：调用服务获取万年历数据 - Step 3: Call service to get calendar data
    const calendarData = lunarService.getCalendarInfo(yearNum, monthNum, dayNum);
    
    // 第四步：返回成功响应 - Step 4: Return success response
    res.json({
      success: true,
      data: calendarData,
      message: '获取万年历信息成功 - Calendar information retrieved successfully'
    });
    
  } catch (error) {
    // 第五步：错误处理 - Step 5: Error handling
    console.error('获取万年历信息失败 - Failed to get calendar info:', error);
    res.status(500).json({
      success: false,
      message: '获取万年历信息失败 - Failed to get calendar information',
      error: error.message
    });
  }
};

/**
 * ============获取今日万年历信息功能开始===========
 * 获取今日万年历信息
 * Get today's calendar information
 * 
 * @param {Object} req - Express请求对象
 * @param {Object} res - Express响应对象
 * @returns {Object} JSON响应包含今日万年历信息
 * 
 * 功能说明：
 * - 自动获取当前日期的万年历信息
 * - 无需用户提供日期参数
 * - 适用于首页展示和快速查询
 * - 提供与指定日期查询相同的详细信息
 * 
 * 使用场景：
 * - 应用首页的今日信息展示
 * - 快速查看当日宜忌
 * - 实时日历信息
 * 
 * 响应格式：
 * {
 *   "success": true,
 *   "data": {
 *     "date": "2024-01-01",
 *     "solar": {...},
 *     "lunar": {...},
 *     "festivals": [...],
 *     "solarTerms": [...],
 *     "suitable": [...],
 *     "avoid": [...]
 *   },
 *   "message": "获取今日万年历信息成功"
 * }
 */
const getTodayCalendarInfo = async (req, res) => {
  try {
    // 第一步：获取当前日期 - Step 1: Get current date
    const today = new Date();
    const year = today.getFullYear();
    const month = today.getMonth() + 1; // JavaScript月份从0开始，需要+1
    const day = today.getDate();
    
    // 第二步：调用服务获取今日万年历数据 - Step 2: Call service to get today's calendar data
    const calendarData = lunarService.getCalendarInfo(year, month, day);
    
    // 第三步：添加日期信息到响应数据 - Step 3: Add date info to response data
    const responseData = {
      ...calendarData,
      currentDate: {
        year,
        month,
        day,
        dateString: `${year}-${month.toString().padStart(2, '0')}-${day.toString().padStart(2, '0')}`
      }
    };
    
    // 第四步：返回成功响应 - Step 4: Return success response
    res.json({
      success: true,
      data: responseData,
      message: '获取今日万年历信息成功 - Today\'s calendar information retrieved successfully'
    });
    
  } catch (error) {
    // 第五步：错误处理 - Step 5: Error handling
    console.error('获取今日万年历信息失败 - Failed to get today\'s calendar info:', error);
    res.status(500).json({
      success: false,
      message: '获取今日万年历信息失败 - Failed to get today\'s calendar information',
      error: error.message
    });
  }
};

/**
 * ============获取月历信息功能开始===========
 * 获取指定月份的月历信息
 * Get monthly calendar information
 * 
 * @param {Object} req - Express请求对象
 * @param {Object} req.query - 查询参数
 * @param {string} req.query.year - 年份（必需）
 * @param {string} req.query.month - 月份（必需）
 * @param {Object} res - Express响应对象
 * @returns {Object} JSON响应包含月历信息
 * 
 * 功能说明：
 * - 获取指定月份的完整日历信息
 * - 包含该月所有日期的基本信息
 * - 标注节日、节气和特殊日期
 * - 适用于月历视图展示
 * 
 * 查询参数：
 * - year: 年份，4位数字
 * - month: 月份，1-12的数字
 * 
 * 响应格式：
 * {
 *   "success": true,
 *   "data": {
 *     "year": 2024,
 *     "month": 1,
 *     "days": [
 *       {
 *         "day": 1,
 *         "lunar": "腊月初十",
 *         "festivals": [...],
 *         "isToday": false
 *       },
 *       ...
 *     ]
 *   },
 *   "message": "获取月历信息成功"
 * }
 */
const getMonthCalendarInfo = async (req, res) => {
  try {
    // 第一步：提取查询参数 - Step 1: Extract query parameters
    const { year, month } = req.query;
    
    // 第二步：参数验证 - Step 2: Parameter validation
    if (!year || !month) {
      return res.status(400).json({
        success: false,
        message: '缺少必要参数：年、月 - Missing required parameters: year, month',
        error: 'MISSING_PARAMETERS'
      });
    }
    
    const yearNum = parseInt(year);
    const monthNum = parseInt(month);
    
    if (isNaN(yearNum) || isNaN(monthNum)) {
      return res.status(400).json({
        success: false,
        message: '参数格式错误：年月必须为数字 - Invalid parameter format: year, month must be numbers',
        error: 'INVALID_FORMAT'
      });
    }
    
    // 第三步：调用服务获取月历数据 - Step 3: Call service to get monthly calendar data
    const monthCalendarData = lunarService.getMonthCalendarInfo(yearNum, monthNum);
    
    // 第四步：返回成功响应 - Step 4: Return success response
    res.json({
      success: true,
      data: monthCalendarData,
      message: '获取月历信息成功 - Monthly calendar information retrieved successfully'
    });
    
  } catch (error) {
    // 第五步：错误处理 - Step 5: Error handling
    console.error('获取月历信息失败 - Failed to get monthly calendar info:', error);
    res.status(500).json({
      success: false,
      message: '获取月历信息失败 - Failed to get monthly calendar information',
      error: error.message
    });
  }
};

/**
 * ============获取吉日信息功能开始===========
 * 获取指定时间范围内的吉日信息
 * Get auspicious days information within specified time range
 * 
 * @param {Object} req - Express请求对象
 * @param {Object} req.query - 查询参数
 * @param {string} req.query.startDate - 开始日期（可选，默认今日）
 * @param {string} req.query.endDate - 结束日期（可选，默认30天后）
 * @param {string} req.query.type - 吉日类型（可选，如结婚、搬家等）
 * @param {Object} res - Express响应对象
 * @returns {Object} JSON响应包含吉日信息
 * 
 * 功能说明：
 * - 查找指定时间范围内的吉日
 * - 支持按事项类型筛选吉日
 * - 提供详细的宜忌说明
 * - 适用于重要事项的日期选择
 * 
 * 查询参数：
 * - startDate: 开始日期，格式YYYY-MM-DD
 * - endDate: 结束日期，格式YYYY-MM-DD
 * - type: 吉日类型，如"结婚"、"搬家"、"开业"等
 * 
 * 响应格式：
 * {
 *   "success": true,
 *   "data": {
 *     "auspiciousDays": [
 *       {
 *         "date": "2024-01-15",
 *         "lunar": "腊月初五",
 *         "suitable": ["结婚", "搬家"],
 *         "avoid": ["动土", "开仓"],
 *         "rating": "大吉"
 *       },
 *       ...
 *     ],
 *     "totalCount": 5
 *   },
 *   "message": "获取吉日信息成功"
 * }
 */
const getAuspiciousDays = async (req, res) => {
  try {
    // 第一步：提取查询参数 - Step 1: Extract query parameters
    const { startDate, endDate, type } = req.query;
    
    // 第二步：设置默认日期范围 - Step 2: Set default date range
    const today = new Date();
    const defaultStartDate = startDate || today.toISOString().split('T')[0];
    const defaultEndDate = endDate || new Date(today.getTime() + 30 * 24 * 60 * 60 * 1000).toISOString().split('T')[0];
    
    // 第三步：调用服务获取吉日数据 - Step 3: Call service to get auspicious days data
    const auspiciousDaysData = lunarService.getAuspiciousDays(defaultStartDate, defaultEndDate, type);
    
    // 第四步：返回成功响应 - Step 4: Return success response
    res.json({
      success: true,
      data: auspiciousDaysData,
      message: '获取吉日信息成功 - Auspicious days information retrieved successfully'
    });
    
  } catch (error) {
    // 第五步：错误处理 - Step 5: Error handling
    console.error('获取吉日信息失败 - Failed to get auspicious days info:', error);
    res.status(500).json({
      success: false,
      message: '获取吉日信息失败 - Failed to get auspicious days information',
      error: error.message
    });
  }
};

/**
 * ============路由端点定义开始===========
 * 定义所有万年历相关的API端点
 * Define all calendar-related API endpoints
 * 
 * 路由说明：
 * - 所有路由都使用GET方法，符合RESTful设计
 * - 路由路径简洁明了，易于理解和使用
 * - 统一的错误处理和响应格式
 */

/**
 * GET /calendar/info - 获取指定日期万年历信息
 * @route GET /calendar/info
 * @access Public
 * @param {string} year - 年份（查询参数）
 * @param {string} month - 月份（查询参数）
 * @param {string} day - 日期（查询参数）
 */
router.get('/info', getCalendarInfo);

/**
 * GET /calendar/today - 获取今日万年历信息
 * @route GET /calendar/today
 * @access Public
 */
router.get('/today', getTodayCalendarInfo);

/**
 * GET /calendar/month - 获取月历信息
 * @route GET /calendar/month
 * @access Public
 * @param {string} year - 年份（查询参数）
 * @param {string} month - 月份（查询参数）
 */
router.get('/month', getMonthCalendarInfo);

/**
 * GET /calendar/auspicious - 获取吉日信息
 * @route GET /calendar/auspicious
 * @access Public
 * @param {string} startDate - 开始日期（查询参数，可选）
 * @param {string} endDate - 结束日期（查询参数，可选）
 * @param {string} type - 吉日类型（查询参数，可选）
 */
router.get('/auspicious', getAuspiciousDays);

/**
 * ============路由导出开始===========
 * 导出路由配置供应用使用
 * Export router configuration for app use
 * 
 * 使用说明：
 * - 在主应用文件中导入此路由配置
 * - 通过 app.use('/api/calendar', calendarRoutes) 挂载到应用
 * - 所有路由将自动获得 /api/calendar 前缀
 * 
 * 示例：
 * import calendarRoutes from './routes/calendar.js';
 * app.use('/api/calendar', calendarRoutes);
 */
export default router;
/**
 * ============万年历路由配置模块结束===========
 */